home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kaboutdata.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  19.3 KB  |  630 lines
  1. /*
  2.  * This file is part of the KDE Libraries
  3.  * Copyright (C) 2000 Espen Sand (espen@kde.org)
  4.  *
  5.  * This library is free software; you can redistribute it and/or
  6.  * modify it under the terms of the GNU Library General Public
  7.  * License as published by the Free Software Foundation; either
  8.  * version 2 of the License, or (at your option) any later version.
  9.  *
  10.  * This library is distributed in the hope that it will be useful,
  11.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  * Library General Public License for more details.
  14.  *
  15.  * You should have received a copy of the GNU Library General Public License
  16.  * along with this library; see the file COPYING.LIB.  If not, write to
  17.  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  * Boston, MA 02110-1301, USA.
  19.  *
  20.  */
  21.  
  22. #include <qvaluelist.h>
  23. #include <qstring.h>
  24. #include <qimage.h>
  25. #include <klocale.h>
  26.  
  27. #ifndef _KABOUTDATA_H_
  28. #define _KABOUTDATA_H_
  29.  
  30. class KAboutPersonPrivate;
  31. class KAboutDataPrivate;
  32.  
  33. /**
  34.  * This structure is used to store information about a person or developer.
  35.  * It can store the person's name, a task, an email address and a
  36.  * link to a home page. This class is intended for use in the
  37.  * KAboutData class, but it can be used elsewhere as well.
  38.  * Normally you should at least define the person's name.
  39.  *
  40.  * Example Usage within a main():
  41.  *
  42.  * \code
  43.  *   KAboutData about("khello", I18N_NOOP("KHello"), "0.1",
  44.  *                   I18N_NOOP("A KDE version of Hello, world!"),
  45.  *                   KAboutData::License_LGPL,
  46.  *                   I18N_NOOP("Copyright (c) 2003 Developer"));
  47.  *
  48.  *   about.addAuthor("Joe Developer", I18N_NOOP("developer"), "joe@host.com", 0);
  49.  *   about.addCredit("Joe User", I18N_NOOP("A lot of bug reports"),
  50.  *                   "joe.user@host.org", 0);
  51.  *   KCmdLineArgs::init(argc, argv, &about);
  52.  * \endcode
  53.  */
  54. class KDECORE_EXPORT KAboutPerson
  55. {
  56. public:
  57.     /**
  58.      * Convenience constructor
  59.      *
  60.      * @param name The name of the person.
  61.      *
  62.      * @param task The task of this person. This string should be
  63.      *              marked for translation, e.g.
  64.      *              I18N_NOOP("Task description....")
  65.      *
  66.      * @param emailAddress The email address of the person.
  67.      *
  68.      * @param webAddress Home page of the person.
  69.      */
  70.     KAboutPerson( const char *name, const char *task,
  71.                   const char *emailAddress, const char *webAddress )
  72.     {
  73.       mName = name;
  74.       mTask = task;
  75.       mEmailAddress = emailAddress;
  76.       mWebAddress = webAddress;
  77.     }
  78.     /**
  79.      * @internal
  80.      * Don't use. Required by QValueList
  81.      */
  82.     KAboutPerson() {}
  83.  
  84.     /**
  85.      * The person's name
  86.      * @return the person's name (can be QString::null, if it has been
  87.      *           constructed with a null name)
  88.      */
  89.     QString name() const;
  90.  
  91.     /**
  92.      * The person's task
  93.      * @return the person's task (can be QString::null, if it has been
  94.      *           constructed with a null task)
  95.      */
  96.     QString task() const;
  97.  
  98.     /**
  99.      * The person's email address
  100.      * @return the person's email address (can be QString::null, if it has been
  101.      *           constructed with a null email)
  102.      */
  103.     QString emailAddress() const;
  104.  
  105.     /**
  106.      * The home page or a relevant link
  107.      * @return the persons home page (can be QString::null, if it has been
  108.      *           constructed with a null home page)
  109.      */
  110.     QString webAddress() const;
  111.  
  112. private:
  113.     const char *mName;
  114.     const char *mTask;
  115.     const char *mEmailAddress;
  116.     const char *mWebAddress;
  117.  
  118.     KAboutPersonPrivate *d;
  119. };
  120.  
  121. class KAboutTranslatorPrivate;
  122. /**
  123.  * This structure is used to store information about a translator.
  124.  * It can store the translator's name and an email address.
  125.  * This class is intended for use in the KAboutData class,
  126.  * but it can be used elsewhere as well.
  127.  * Normally you should at least define the translator's name.
  128.  *
  129.  * It's not possible to use KAboutPerson for this, because
  130.  * KAboutPerson stores internally only const char* pointers, but the
  131.  * translator information is generated dynamically from the translation
  132.  * of a dummy string.
  133. */
  134. class KDECORE_EXPORT KAboutTranslator
  135. {
  136. public:
  137.     /**
  138.      * Convenience constructor
  139.      *
  140.      * @param name The name of the person.
  141.      *
  142.      * @param emailAddress The email address of the person.
  143.      */
  144.     KAboutTranslator(const QString & name=QString::null,
  145.                      const QString & emailAddress=QString::null);
  146.  
  147.     /**
  148.      * The translator's name
  149.      * @return the translators's name (can be QString::null, if it has been
  150.      *           constructed with a null name)
  151.      */
  152.     QString name() const;
  153.  
  154.     /**
  155.      * The translator's email
  156.      * @return the translator's email address (can be QString::null, if it has been
  157.      *           constructed with a null email)
  158.      */
  159.     QString emailAddress() const;
  160.  
  161. private:
  162.     QString mName;
  163.     QString mEmail;
  164.     KAboutTranslatorPrivate* d;
  165. };
  166.  
  167.  
  168. /**
  169.  * This class is used to store information about a program. It can store
  170.  * such values as version number, program name, home page, email address
  171.  * for bug reporting, multiple authors and contributors
  172.  * (using KAboutPerson), license and copyright information.
  173.  *
  174.  * Currently, the values set here are shown by the "About" box
  175.  * (see KAboutDialog), used by the bug report dialog (see KBugReport),
  176.  * and by the help shown on command line (see KCmdLineArgs).
  177.  *
  178.  * @short Holds information needed by the "About" box and other
  179.  * classes.
  180.  * @author Espen Sand (espen@kde.org), David Faure (faure@kde.org)
  181.  */
  182. class KDECORE_EXPORT KAboutData
  183. {
  184.   public:
  185.   /**
  186.    * Descibes the license of the software.
  187.    */
  188.     enum LicenseKey
  189.     {
  190.       License_Custom = -2,
  191.       License_File = -1,
  192.       License_Unknown = 0,
  193.       License_GPL  = 1,
  194.       License_GPL_V2 = 1,
  195.       License_LGPL = 2,
  196.       License_LGPL_V2 = 2,
  197.       License_BSD  = 3,
  198.       License_Artistic = 4,
  199.       License_QPL = 5,
  200.       License_QPL_V1_0 = 5
  201.     };
  202.  
  203.   public:
  204.     /**
  205.      * Constructor.
  206.      *
  207.      * @param appName The program name used internally. Example: "kedit"
  208.      *
  209.      * @param programName A displayable program name string. This string
  210.      *        should be marked for translation. Example: I18N_NOOP("KEdit")
  211.      *
  212.      * @param version The program version string.
  213.      *
  214.      * @param shortDescription A short description of what the program does.
  215.      *        This string should be marked for translation.
  216.      *        Example: I18N_NOOP("A simple text editor.")
  217.      *
  218.      * @param licenseType The license identifier. Use setLicenseText if
  219.      *        you use a license not predefined here.
  220.      *
  221.      * @param copyrightStatement A copyright statement, that can look like this:
  222.      *        "(c) 1999-2000, Name". The string specified here is not modified
  223.      *        in any manner. The author information from addAuthor is not
  224.      *        used.
  225.      *
  226.      * @param text Some free form text, that can contain any kind of
  227.      *        information. The text can contain newlines. This string
  228.      *        should be marked for translation.
  229.      *
  230.      * @param homePageAddress The program homepage string.
  231.      *        Start the address with "http://". "http://some.domain" is
  232.      *        is correct, "some.domain" is not.
  233.      *
  234.      * @param bugsEmailAddress The bug report email address string.
  235.      *        This defaults to the kde.org bug system.
  236.      *
  237.      */
  238.     KAboutData( const char *appName,
  239.                 const char *programName,
  240.         const char *version,
  241.         const char *shortDescription = 0,
  242.         int licenseType = License_Unknown,
  243.         const char *copyrightStatement = 0,
  244.         const char *text = 0,
  245.         const char *homePageAddress = 0,
  246.         const char *bugsEmailAddress = "submit@bugs.kde.org"
  247.         );
  248.  
  249.      ~KAboutData();
  250.  
  251.     /**
  252.      * Defines an author. You can call this function as many times you
  253.      * need. Each entry is appended to a list. The person in the first entry
  254.      * is assumed to be the leader of the project.
  255.      *
  256.      * @param name The developer's name in UTF-8 encoding.
  257.      *
  258.      * @param task What the person is responsible for. This text can contain
  259.      *             newlines. It should be marked for translation like this:
  260.      *             I18N_NOOP("Task description..."). Can be 0.
  261.      *
  262.      * @param emailAddress An Email address where the person can be reached.
  263.      *                     Can be 0.
  264.      *
  265.      * @param webAddress The person's homepage or a relevant link.
  266.      *        Start the address with "http://". "http://some.domain" is
  267.      *        correct, "some.domain" is not. Can be 0.
  268.      *
  269.      */
  270.     void addAuthor( const char *name,
  271.             const char *task=0,
  272.             const char *emailAddress=0,
  273.             const char *webAddress=0 );
  274.  
  275.     /**
  276.      * Defines a person that deserves credit. You can call this function
  277.      * as many times you need. Each entry is appended to a list.
  278.      *
  279.      * @param name The person's name in UTF-8 encoding.
  280.      *
  281.      * @param task What the person has done to deserve the honor. The
  282.      *        text can contain newlines. It should be marked for
  283.      *        translation like this: I18N_NOOP("Task description...")
  284.      *        Can be 0.
  285.      *
  286.      * @param emailAddress An Email address when the person can be reached.
  287.      *        Can be 0.
  288.      *
  289.      * @param webAddress The person's homepage or a relevant link.
  290.      *        Start the address with "http://". "http://some.domain" is
  291.      *        is correct, "some.domain" is not. Can be 0.
  292.      *
  293.      */
  294.     void addCredit( const char *name,
  295.                     const char *task=0,
  296.             const char *emailAddress=0,
  297.             const char *webAddress=0 );
  298.  
  299.     /**
  300.      * Sets the name of the translator of the gui. Since this depends
  301.      * on the language, just use a dummy text marked for translation.
  302.      *
  303.      * For example:
  304.      * \code
  305.      * setTranslator(I18N_NOOP("_: NAME OF TRANSLATORS\\nYour names")
  306.      * ,I18N_NOOP("_: EMAIL OF TRANSLATORS\\nYour emails"));
  307.      * \endcode
  308.      *
  309.      * The translator can then translate this dummy text with his name
  310.      * or with a list of names separated with ",".
  311.      * If there is no translation or the application is used with the
  312.      * default language, this function call is ignored.
  313.      *
  314.      * Note: If you are using the default KDE automake environment,
  315.      * there is no need to use this function, because the two
  316.      * default strings above are added to the applications po file
  317.      * automatically.
  318.      *
  319.      * @param name the name of the translator
  320.      * @param emailAddress the email address of the translator
  321.      * @see KAboutTranslator
  322.      */
  323.     void setTranslator(const char* name, const char* emailAddress);
  324.  
  325.     /**
  326.      * Defines a license text.
  327.      *
  328.      * The text will be translated if it got marked for
  329.      * translations with the I18N_NOOP() macro.
  330.      *
  331.      * Example:
  332.      * \code
  333.      * setLicenseText( I18N_NOOP("This is my license"));
  334.      * \endcode
  335.      *
  336.      * NOTE: No copy of the text is made.
  337.      *
  338.      * @param license The license text in utf8 encoding.
  339.      */
  340.     void setLicenseText( const char *license );
  341.  
  342.     /**
  343.      * Defines a license text.
  344.      *
  345.      * @param file File containing the license text.
  346.      */
  347.     void setLicenseTextFile( const QString &file );
  348.  
  349.     /**
  350.      * Defines the program name used internally.
  351.      *
  352.      * @param appName The application name. Example: "kate".
  353.      */
  354.     void setAppName( const char *appName );
  355.     
  356.     /**
  357.      * Defines the displayable program name string.
  358.      *
  359.      * @param programName The program name. This string should be
  360.      *        marked for translation.
  361.      *        Example: I18N_NOOP("Advanced Text Editor").
  362.      * @since 3.2
  363.      */
  364.     void setProgramName( const char* programName );
  365.  
  366.     /**
  367.      * Defines the program logo.
  368.      * Use this if you need to have application logo 
  369.      * in AboutData other than application icon.
  370.      *
  371.      * @param image logo image.
  372.      * @see programLogo()
  373.      * @since 3.4
  374.     */
  375.     void setProgramLogo(const QImage& image);
  376.  
  377.     /**
  378.      * Defines the program version string.
  379.      *
  380.      * @param version The program version.
  381.      */
  382.     void setVersion( const char* version );
  383.     
  384.     /**
  385.      * Defines a short description of what the program does.
  386.      *
  387.      * @param shortDescription The program description This string should be marked
  388.      *        for translation. Example: I18N_NOOP("An advanced text editor
  389.      *        with syntax highlithing support.").
  390.      */
  391.     void setShortDescription( const char *shortDescription );
  392.     
  393.     /**
  394.      * Defines the license identifier.
  395.      *
  396.      * @param licenseKey The license identifier.
  397.      */
  398.     void setLicense( LicenseKey licenseKey);
  399.     
  400.     /**
  401.      * Defines the copyright statement to show when displaying the license.
  402.      *
  403.      * @param copyrightStatement A copyright statement, that can look like
  404.      *        this: "(c) 1999-2000, Name". The string specified here is not
  405.      *        modified in any manner. The author information from addAuthor
  406.      *        is not used.
  407.      */
  408.     void setCopyrightStatement( const char *copyrightStatement );
  409.     
  410.     /**
  411.      * Defines the additional text to show in the about dialog.
  412.      *
  413.      * @param otherText Some free form text, that can contain any kind of
  414.      *        information. The text can contain newlines. This string
  415.      *        should be marked for translation.
  416.      */
  417.     void setOtherText( const char *otherText );
  418.     
  419.     /**
  420.      * Defines the program homepage.
  421.      *
  422.      * @param homepage The program homepage string.
  423.      *        Start the address with "http://". "http://kate.kde.org" is
  424.      *        is correct, "kde.kde.org" is not.
  425.      */
  426.     void setHomepage( const char *homepage );
  427.     
  428.     /**
  429.      * Defines the address where bug reports should be sent.
  430.      *
  431.      * @param bugAddress The bug report email address string.
  432.      *        This defaults to the kde.org bug system.
  433.      */
  434.     void setBugAddress( const char *bugAddress );
  435.     
  436.     /**
  437.      * Defines the product name wich will be used in the KBugReport dialog.
  438.      * By default it's the appName, but you can overwrite it here to provide
  439.      * support for special components e.g. 'product/component' like
  440.      * 'kontact/summary'.
  441.      *
  442.      * @param name The name of product
  443.      */
  444.     void setProductName( const char *name );
  445.  
  446.     /**
  447.      * Returns the application's internal name.
  448.      * @return the internal program name.
  449.      */
  450.     const char *appName() const;
  451.  
  452.     /**
  453.      * Returns the application's product name, which will be used in KBugReport
  454.      * dialog. By default it returns appName(), otherwise the one which is set
  455.      * with setProductName()
  456.      * 
  457.      * @return the product name.
  458.      */
  459.     const char *productName() const;
  460.  
  461.     /**
  462.      * Returns the translated program name.
  463.      * @return the program name (translated).
  464.      */
  465.     QString programName() const;
  466.  
  467.     /**
  468.      * @internal
  469.      */
  470.     const char* internalProgramName() const;
  471.     /**
  472.      * @internal
  473.      */
  474.     void translateInternalProgramName() const;
  475.  
  476.     /**
  477.      * Returns the program logo image. 
  478.      * @return the program logo data or null image if there is 
  479.      * no custom application logo defined.
  480.      * @since 3.4
  481.      */
  482.     QImage programLogo() const;
  483.  
  484.     /**
  485.      * Returns the program's version.
  486.      * @return the version string.
  487.      */
  488.     QString version() const;
  489.  
  490.     /**
  491.      * @internal
  492.      */
  493.     const char* internalVersion() const { return mVersion; }
  494.  
  495.     /**
  496.      * Returns a short, translated description.
  497.      * @return the short description (translated). Can be
  498.      *         QString::null if not set.
  499.      */
  500.     QString shortDescription() const;
  501.  
  502.     /**
  503.      * Returns the application homepage.
  504.      * @return the application homepage URL. Can be QString::null if
  505.      *         not set.
  506.      */
  507.     QString homepage() const;
  508.  
  509.     /**
  510.      * Returns the email address for bugs.
  511.      * @return the email address where to report bugs.
  512.      */
  513.     QString bugAddress() const;
  514.     
  515.     /**
  516.      * @internal
  517.      */
  518.     const char* internalBugAddress() const { return mBugEmailAddress; }
  519.  
  520.     /**
  521.      * Returns a list of authors.
  522.      * @return author information (list of persons).
  523.      */
  524.     const QValueList<KAboutPerson> authors() const;
  525.  
  526.     /**
  527.      * Returns a list of persons who contributed.
  528.      * @return credit information (list of persons).
  529.      */
  530.     const QValueList<KAboutPerson> credits() const;
  531.  
  532.     /**
  533.      * Returns a list of translators.
  534.      * @return translators information (list of persons)
  535.      */
  536.     const QValueList<KAboutTranslator> translators() const;
  537.  
  538.     /**
  539.      * Returns a message about the translation team.
  540.      * @return a message about the translation team
  541.      */
  542.     static QString aboutTranslationTeam();
  543.  
  544.     /**
  545.      * Returns a translated, free form text.
  546.      * @return the free form text (translated). Can be QString::null if not set.
  547.      */
  548.     QString otherText() const;
  549.  
  550.     /**
  551.      * Returns the license. If the licenseType argument of the constructor has been
  552.      * used, any text defined by setLicenseText is ignored,
  553.      * and the standard text for the chosen license will be returned.
  554.      *
  555.      * @return The license text.
  556.      */
  557.     QString license() const;
  558.  
  559.     /**
  560.      * Returns the copyright statement.
  561.      * @return the copyright statement. Can be QString::null if not set.
  562.      */
  563.     QString copyrightStatement() const;
  564.  
  565.     /**
  566.      * Returns the plain text displayed around the list of authors instead
  567.      * of the default message telling users to send bug reports to bugAddress().
  568.      *
  569.      * @return the plain text displayed around the list of authors instead
  570.      *         of the default message.  Can be QString::null.
  571.      */
  572.     QString customAuthorPlainText() const;
  573.  
  574.     /**
  575.      * Returns the rich text displayed around the list of authors instead
  576.      * of the default message telling users to send bug reports to bugAddress().
  577.      *
  578.      * @return the rich text displayed around the list of authors instead
  579.      *         of the default message.  Can be QString::null.
  580.      */
  581.     QString customAuthorRichText() const;
  582.  
  583.     /**
  584.      * Returns whether custom text should be displayed around the list of
  585.      * authors.
  586.      *
  587.      * @return whether custom text should be displayed around the list of
  588.      *         authors.
  589.      */
  590.     bool customAuthorTextEnabled() const;
  591.     
  592.     /**
  593.      * Sets the custom text displayed around the list of authors instead
  594.      * of the default message telling users to send bug reports to bugAddress().
  595.      *
  596.      * @param plainText The plain text.
  597.      * @param richText The rich text.
  598.      *
  599.      * Both parameters can be QString::null to not display any message at
  600.      * all.  Call unsetCustomAuthorText() to revert to the default mesage.
  601.      */
  602.     void setCustomAuthorText(const QString &plainText, const QString &richText);
  603.     
  604.     /**
  605.      * Clears any custom text displayed around the list of authors and falls
  606.      * back to the default message telling users to send bug reports to
  607.      * bugAddress().
  608.      */
  609.     void unsetCustomAuthorText();
  610.     
  611.   private:
  612.     const char *mAppName;
  613.     const char *mProgramName;
  614.     const char *mVersion;
  615.     const char *mShortDescription;
  616.     int mLicenseKey;
  617.     const char *mCopyrightStatement;
  618.     const char *mOtherText;
  619.     const char *mHomepageAddress;
  620.     const char *mBugEmailAddress;
  621.     QValueList<KAboutPerson> mAuthorList;
  622.     QValueList<KAboutPerson> mCreditList;
  623.     const char *mLicenseText;
  624.  
  625.     KAboutDataPrivate *d;
  626. };
  627.  
  628. #endif
  629.  
  630.